<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Purpose and usage</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch01.html" title="Chapter 1. About the library"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Purpose and usage</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 1. About the library</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Purpose and usage"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2472320"></a>Purpose and usage</h2></div></div></div>
            
            <p>The purpose of the library is to make it possible to (very) easily create dynamic
                images (a.k.a. graphs) using PHP scripting. The library hides as much as possible
                all the details necessary to create dynamic images. Strictly speaking all the basic
                low level functionality to draw images are already available in PHP since PHP comes
                with the core GD library which is the very lowest layer to create images. The GD
                library has graphic primitives to create lines, circles, points etc. but it has no
                built-in intelligence to handle scales, labelling , colors etc. This logically makes
                JpGraph library a higher type library more easily accessible than the raw GD
                library. </p>
            <div class="figure"><a name="id2472478"></a><p class="title"><b>Figure 1.1. JpGraph and PHP</b></p><div class="figure-contents">
                
                <div class="mediaobject"><img src="images/jpgraph-and-php.png" alt="JpGraph and PHP"></div>
            </div></div><br class="figure-break">
            <p>There are several possible usage scenario for the library and it's different
                parts. </p>
            <p>The most common usage is most likely to visualize numeric data by creating basic
                charts (for example line, bar or pie charts) that is included dynamically in a
                WEB-page via a straight forward <code class="code">&lt;img&gt;</code> tag. The details on how to
                create dynamic graphs will be fully covered in later sections of this manual The
                library itself is agnostic to where the data comes from so it could for example be
                retrieved from a database, from a plain text file or perhaps from some WEB-service.
                In addition to this scenario the library could be used as a tool to create dynamic
                charts that are stored as image files in a directory. This makes it possible to use
                the library in an off-line batch mode from the command line (most likely using the
                cli =command line version of PHP). For an example of using JpGraph in batch mode see <a class="xref" href="ch34.html" title="Chapter 34. Showing SPAM statistics">Chapter 34. <i>Showing SPAM statistics</i></a>.</p>
            <p>In addition to these basic usage scenarios both the free and the slightly more
                advanced pro-version of the library includes a multitude of additional functionality
                which includes for example more advanced graph types (like spider graphs, polar
                plots, contour plots etc.) and some non graph capabilities like the possibility to
                create barcodes (only available in the pro-version) or to create Gantt-charts. The
                usage of all of these types of graphs are explained in this manual.</p>
            <p>
                </p><div class="caution" title="Caution" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Caution</h3>
                    <p>In order to use JpGraph the PHP installation must have support for the GD
                        libraries enabled. See Chapter 2 and 3 for details on checking the
                        installation.</p>
                </div><p>
            </p>
            <p>In order to get a quick feel for how the library can be used we have included in <a class="xref" href="ch01s04.html#example.example0" title="Example 1.1. This is the very first example (example0.php)">Example 1.1. This is the very first example (<code class="filename">example0.php</code>) </a> a very basic type of line graph. Don't worry
                right now about the details, the message here is that it only takes six lines of
                real script code to create a basic graph. Have a look at the example and see just
                how much of the script makes sense without us even having discussed any API
                yet.</p>
            <div class="example"><a name="example.example0"></a><p class="title"><b>Example 1.1. This is the very first example (<code class="filename">example0.php</code>) </b></p><div class="example-contents">  <div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-inlinetags">&lt;?php</span><span class="hl-code"> </span><span class="hl-comment">//</span><span class="hl-comment"> content=&quot;text/plain; charset=utf-8&quot;</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-reserved">require_once</span><span class="hl-code"> </span><span class="hl-brackets">(</span><span class="hl-quotes">'</span><span class="hl-string">jpgraph/jpgraph.php</span><span class="hl-quotes">'</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-reserved">require_once</span><span class="hl-code"> </span><span class="hl-brackets">(</span><span class="hl-quotes">'</span><span class="hl-string">jpgraph/jpgraph_line.php</span><span class="hl-quotes">'</span><span class="hl-brackets">)</span><span class="hl-code">;
 
</span><span class="hl-comment">//</span><span class="hl-comment"> Some data</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$ydata</span><span class="hl-code"> = </span><span class="hl-reserved">array</span><span class="hl-brackets">(</span><span class="hl-number">11</span><span class="hl-code">,</span><span class="hl-number">3</span><span class="hl-code">,</span><span class="hl-number">8</span><span class="hl-code">,</span><span class="hl-number">12</span><span class="hl-code">,</span><span class="hl-number">5</span><span class="hl-code">,</span><span class="hl-number">1</span><span class="hl-code">,</span><span class="hl-number">9</span><span class="hl-code">,</span><span class="hl-number">13</span><span class="hl-code">,</span><span class="hl-number">5</span><span class="hl-code">,</span><span class="hl-number">7</span><span class="hl-brackets">)</span><span class="hl-code">;
 
</span><span class="hl-comment">//</span><span class="hl-comment"> Create the graph. These two calls are always required</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$graph</span><span class="hl-code"> = </span><span class="hl-reserved">new</span><span class="hl-code"> </span><span class="hl-identifier">Graph</span><span class="hl-brackets">(</span><span class="hl-number">350</span><span class="hl-code">,</span><span class="hl-number">250</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-var">$graph</span><span class="hl-code">-&gt;</span><span class="hl-identifier">SetScale</span><span class="hl-brackets">(</span><span class="hl-quotes">'</span><span class="hl-string">textlin</span><span class="hl-quotes">'</span><span class="hl-brackets">)</span><span class="hl-code">;
 
</span><span class="hl-comment">//</span><span class="hl-comment"> Create the linear plot</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$lineplot</span><span class="hl-code">=</span><span class="hl-reserved">new</span><span class="hl-code"> </span><span class="hl-identifier">LinePlot</span><span class="hl-brackets">(</span><span class="hl-var">$ydata</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-var">$lineplot</span><span class="hl-code">-&gt;</span><span class="hl-identifier">SetColor</span><span class="hl-brackets">(</span><span class="hl-quotes">'</span><span class="hl-string">blue</span><span class="hl-quotes">'</span><span class="hl-brackets">)</span><span class="hl-code">;
 
</span><span class="hl-comment">//</span><span class="hl-comment"> Add the plot to the graph</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$graph</span><span class="hl-code">-&gt;</span><span class="hl-identifier">Add</span><span class="hl-brackets">(</span><span class="hl-var">$lineplot</span><span class="hl-brackets">)</span><span class="hl-code">;
 
</span><span class="hl-comment">//</span><span class="hl-comment"> Display the graph</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$graph</span><span class="hl-code">-&gt;</span><span class="hl-identifier">Stroke</span><span class="hl-brackets">(</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-inlinetags">?&gt;</span></pre></td></tr></table></div></div></div><br class="example-break">  <div class="figure"><a name="fig.example0"></a><p class="title"><b>Figure 1.2. This is the very first example <code class="uri"><a class="uri" href="example_src/example0.html" target="_top">(<code class="filename">example0.php</code>)</a></code> </b></p><div class="figure-contents">  <span class="inlinemediaobject"><img src="images/example0.png" alt="This is the very first example (example0.php)"></span> </div></div><br class="figure-break">
        </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch01.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>
